React useFormStatus: Цялостно ръководство за управление на състоянието на формуляри

Куката useFormStatus, въведена в React 18, предоставя мощен и ефективен начин за управление на състоянието на изпращане на формуляри в рамките на React Server Components. Тази кука е специално проектирана да работи със сървърни действия (server actions), предлагайки безпроблемна интеграция за обработка на изпращания на формуляри директно на сървъра. Тя опростява процеса на проследяване на статуса на изпращане на формуляр, предоставяйки ценна информация като например дали формулярът е в процес на изчакване, дали е изпратен успешно или е възникнала грешка. Това ръководство изследва възможностите на useFormStatus, неговите предимства и практически примери, демонстриращи употребата му в различни сценарии.

Разбиране на Server Actions и useFormStatus

Преди да се потопим в useFormStatus, е изключително важно да разберем React Server Components и Server Actions. Server Actions ви позволяват да дефинирате функции, които се изпълняват на сървъра и са директно достъпни от вашите React компоненти. Това позволява обработка на изпращания на формуляри, извличане на данни и други операции от страна на сървъра без необходимост от отделна API крайна точка.

Куката useFormStatus след това предоставя информация за изпълнението на тези Server Actions, задействани от изпращания на формуляри.

Какво е useFormStatus?

useFormStatus е React кука, която връща обект, съдържащ информация за статуса на последното изпращане на формуляр. Тази информация включва:

• pending: Булева стойност, показваща дали формулярът в момента се изпраща.
• data: Обектът FormData, свързан с изпращането.
• method: HTTP методът, използван за изпращането (обикновено 'POST').
• action: Функцията Server Action, която е била задействана.

Предимства от използването на useFormStatus

Използването на useFormStatus предлага няколко ключови предимства:

• Опростено управление на състоянието: Елиминира нуждата от ръчно управление на състоянието за проследяване на статуса на изпращане на формуляра. Куката се актуализира автоматично с напредването на процеса.
• Подобрено потребителско изживяване: Предоставя обратна връзка в реално време на потребителите, като показване на индикатори за зареждане, докато формулярът се обработва, или показване на съобщения за грешки при неуспех.
• Чист код: Насърчава по-декларативна и поддържаема кодова база чрез разделяне на логиката за изпращане на формуляра от рендирането на компонента.
• Безпроблемна интеграция със Server Actions: Проектирана е да работи перфектно със Server Actions, което улеснява обработката на изпращания на формуляри директно на сървъра.

Практически примери за useFormStatus

Нека разгледаме няколко практически примера, за да илюстрираме употребата на useFormStatus в различни сценарии.

Основно изпращане на формуляр с индикатор за зареждане

Този пример демонстрира прост формуляр с индикатор за зареждане, който се показва, докато формулярът се изпраща.

Server Action (actions.js):

'use server'

export async function submitForm(formData) {
  // Симулиране на забавяне за демонстрация на състоянието на зареждане
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Form submitted with name:', name);
  return { message: `Формулярът е изпратен успешно с име: ${name}` };
}

React компонент (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'

function FormComponent() {
  const { pending } = useFormStatus()

  return (
    

      Име:
      
      
        {pending ? 'Изпращане...' : 'Изпрати'}
      
    
  )
}

export default FormComponent

В този пример свойството pending от useFormStatus се използва, за да се деактивират полето за въвеждане и бутонът, докато формулярът се изпраща, и за да се покаже съобщение „Изпращане...“.

Обработка на състояния на успех и грешка

Този пример демонстрира как да се обработват състояния на успех и грешка след изпращане на формуляра.

Server Action (actions.js):

'use server'

export async function submitForm(formData) {
  // Симулиране на забавяне
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');

  if (!name) {
    throw new Error('Името е задължително');
  }

  console.log('Form submitted with name:', name);
  return { message: `Формулярът е изпратен успешно с име: ${name}` };
}

React компонент (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await submitForm(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Име:
      
      
        {pending ? 'Изпращане...' : 'Изпрати'}
      
      {pending && 
Изпращане...
}
      {message && 
{message}
}
      {error && 
Грешка: {error}
}
    
  )
}

export default FormComponent

В този пример се използва блок try/catch във функцията handleSubmit. Ако Server Action хвърли грешка, тя се улавя и се показва на потребителя. При успешно изпращане се показва съобщение за успех.

Използване на FormData за сложни данни

useFormStatus работи безпроблемно с FormData, което ви позволява лесно да обработвате сложни структури от данни. Ето пример, който показва как да качвате файлове.

Server Action (actions.js):

'use server'

export async function uploadFile(formData) {
  // Симулиране на обработка на файл
  await new Promise(resolve => setTimeout(resolve, 2000));

  const file = formData.get('file');

  if (!file) {
    throw new Error('Няма качен файл');
  }

  console.log('File uploaded:', file.name);
  return { message: `Файлът е качен успешно: ${file.name}` };
}

React компонент (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { uploadFile } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await uploadFile(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Качи файл:
      
      
        {pending ? 'Качване...' : 'Качи'}
      
      {pending && 
Качване...
}
      {message && 
{message}
}
      {error && 
Грешка: {error}
}
    
  )
}

export default FormComponent

Този пример демонстрира как да се обработват качвания на файлове с помощта на FormData. Сървърното действие извлича файла от обекта FormData и го обработва. Куката useFormStatus управлява състоянието на зареждане, докато файлът се качва.

Най-добри практики за използване на useFormStatus

За да се възползвате максимално от предимствата на useFormStatus, обмислете следните най-добри практики:

• Предоставяйте ясна обратна връзка на потребителя: Използвайте състоянието pending, за да показвате информативни индикатори за зареждане и да деактивирате елементи на формуляра, за да предотвратите многократни изпращания.
• Обработвайте грешките елегантно: Внедрете обработка на грешки, за да улавяте изключения във вашите Server Actions и да показвате лесни за разбиране съобщения за грешки.
• Валидирайте данните на сървъра: Извършвайте валидация от страна на сървъра, за да гарантирате целостта и сигурността на данните.
• Поддържайте Server Actions кратки: Фокусирайте Server Actions върху конкретни задачи, за да подобрите производителността и поддръжката.
• Помислете за достъпността: Уверете се, че вашите формуляри са достъпни, като предоставите подходящи етикети, ARIA атрибути и поддръжка за навигация с клавиатура.

Напреднали случаи на употреба

Освен основните примери, useFormStatus може да се използва и в по-сложни сценарии:

• Прогресивно подобряване: Използвайте Server Actions и useFormStatus, за да подобрявате прогресивно вашите формуляри, предоставяйки основно изживяване за потребители с деактивиран JavaScript и по-богато изживяване за тези с активиран JavaScript.
• Оптимистични актуализации: Внедрете оптимистични актуализации, като актуализирате потребителския интерфейс веднага след изпращането на формуляра, приемайки, че изпращането ще бъде успешно. Върнете актуализацията, ако изпращането се провали.
• Интеграция с библиотеки за формуляри: Интегрирайте useFormStatus с популярни библиотеки за формуляри като Formik или React Hook Form, за да управлявате състоянието и валидацията на формуляра. Въпреки че тези библиотеки често имат собствено управление на състоянието, useFormStatus може да бъде полезен за финалната фаза на изпращане към сървърно действие.

Съображения за интернационализация (i18n)

При изграждането на формуляри за глобална аудитория, интернационализацията (i18n) е от решаващо значение. Ето как да вземете предвид i18n, когато използвате useFormStatus:

• Локализирани съобщения за грешки: Уверете се, че съобщенията за грешки, показвани на потребителя, са локализирани на предпочитания от него език. Това може да се постигне чрез съхраняване на съобщенията за грешки във файлове за превод и използване на библиотека като react-intl или i18next за извличане на подходящия превод.
• Форматиране на дати и числа: Обработвайте форматирането на дати и числа според локала на потребителя. Използвайте библиотеки като Intl.DateTimeFormat и Intl.NumberFormat, за да форматирате тези стойности правилно.
• Поддръжка отдясно наляво (RTL): Ако вашето приложение поддържа езици, които се пишат отдясно наляво (напр. арабски, иврит), уверете се, че вашите формуляри са правилно стилизирани, за да се адаптират към RTL оформления.
• Валидация на формуляри: Адаптирайте правилата за валидация на формуляри към различни локали. Например, валидацията на телефонен номер може да варира значително в различните държави.

Пример за локализирани съобщения за грешки:

// translations/en.json
{
  "form.error.nameRequired": "Please enter your name.",
  "form.success.submission": "Thank you for your submission!"
}

// translations/fr.json
{
  "form.error.nameRequired": "Veuillez entrer votre nom.",
  "form.success.submission": "Merci pour votre soumission !"
}

// Компонент, използващ react-intl
import { useIntl } from 'react-intl';

function FormComponent() {
  const intl = useIntl();
  const [error, setError] = useState(null);

  // ...

  catch (e) {
    setError(intl.formatMessage({ id: 'form.error.nameRequired' }));
  }
}

Съображения за достъпност

Достъпността е ключов аспект при изграждането на приобщаващи уеб приложения. Ето няколко съображения за достъпност, които трябва да имате предвид, когато използвате useFormStatus:

• ARIA атрибути: Използвайте ARIA атрибути, за да предоставите на помощните технологии информация за статуса на формуляра. Например, използвайте aria-busy="true" на бутона за изпращане, докато формулярът е в процес на изчакване.
• Етикети: Уверете се, че всички полета на формуляра имат ясни и описателни етикети, които са свързани с елементите за въвеждане чрез елемента <label>.
• Съобщения за грешки: Показвайте съобщенията за грешки по начин, който е лесно забележим и разбираем от потребители с увреждания. Използвайте ARIA атрибути като aria-live="assertive", за да обявявате съобщенията за грешки на екранните четци.
• Навигация с клавиатура: Уверете се, че потребителите могат да навигират във формуляра само с помощта на клавиатурата. Използвайте атрибута tabindex, за да контролирате реда, в който елементите получават фокус.
• Цветен контраст: Уверете се, че цветовете на текста и фона, използвани във формуляра, имат достатъчен контраст, за да бъдат лесно четими от потребители със зрителни увреждания.

useFormStatus срещу традиционното управление на състоянието

Традиционно, React разработчиците са управлявали състоянието на изпращане на формуляри, използвайки състояние на компонента (useState) или по-сложни библиотеки за управление на състоянието (напр. Redux, Zustand). Ето сравнение на тези подходи с useFormStatus:

Характеристика	useFormStatus	useState	Външно управление на състоянието
Сложност	Ниска	Средна	Висока
Интеграция със Server Actions	Безпроблемна	Изисква ръчна интеграция	Изисква ръчна интеграция
Шаблонен код (Boilerplate)	Минимален	Умерен	Значителен
Подходящи случаи на употреба	Формуляри, изпращащи се директно към Server Actions	Прости формуляри с ограничено състояние	Сложни формуляри със споделено състояние между компоненти

useFormStatus се откроява, когато вашите формуляри взаимодействат директно с React Server Actions. Той намалява шаблонния код и опростява процеса. Въпреки това, за много сложни формуляри със състояние, споделено между множество компоненти, все още може да е оправдано използването на пълноценна библиотека за управление на състоянието.

Отстраняване на често срещани проблеми

Ето някои често срещани проблеми, които може да срещнете при използването на useFormStatus, и как да ги отстраните:

• useFormStatus не се актуализира:
  • Уверете се, че използвате useFormStatus в елемент <form>, чийто action prop е настроен на Server Action.
  • Проверете дали Server Action е правилно дефиниран и експортиран.
  • Проверете за грешки в Server Action, които може да му пречат да завърши успешно.
• Съобщенията за грешки не се показват:
  • Уверете се, че правилно улавяте грешките във вашия Server Action и връщате съобщение за грешка.
  • Проверете дали показвате съобщението за грешка във вашия компонент, използвайки състоянието error.
• Индикаторът за зареждане не се появява:
  • Уверете се, че използвате състоянието pending от useFormStatus, за да показвате условно индикатора за зареждане.
  • Проверете дали Server Action действително отнема известно време за изпълнение (напр. чрез симулиране на забавяне).

Заключение

useFormStatus предоставя чист и ефективен начин за управление на състоянието на изпращане на формуляри в React приложения, използващи Server Components. Като се възползвате от тази кука, можете да опростите кода си, да подобрите потребителското изживяване и да се интегрирате безпроблемно със Server Actions. Това ръководство обхвана основите на useFormStatus, предостави практически примери и обсъди най-добрите практики за ефективното му използване. Чрез включването на useFormStatus във вашите React проекти, можете да оптимизирате обработката на формуляри и да изграждате по-стабилни и лесни за използване приложения за глобална аудитория.